Add Temporal Nexus Operation Handler by Quinn-With-Two-Ns · Pull Request #2842 · temporalio/sdk-java

Quinn-With-Two-Ns · 2026-04-14T19:03:08Z

Add TemporalOperationHandler for generic Nexus operations

Goal

Provide a new base to make it easy to expose more Temporal actions as Nexus Operations

Summary

Adds TemporalOperationHandler, a generic OperationHandler implementation that maps Nexus operations to Temporal workflows via a composable StartFunction
Adds TemporalNexusClient for starting workflows (typed and untyped) from within Nexus operation handlers
Supports subclassing TemporalOperationHandler to customize cancel behavior by overriding cancelWorkflowRun
Extracts shared workflow start logic into NexusStartWorkflowHelper, reused by both WorkflowRunOperation and the new handler

Test plan

GenericHandlerTypedStartWorkflowTest — typed workflow with return value
GenericHandlerTypedProcTest — typed void workflow
GenericHandlerUntypedStartWorkflowTest — untyped workflow start
GenericHandlerSyncResultTest — synchronous result path
GenericHandlerCancelTest — cancel with default and custom behavior

Note

Medium Risk
Touches Nexus operation start/cancel and workflow lifecycle from handlers; behavior changes are mostly additive behind experimental APIs, but refactors WorkflowRunOperationImpl and token parsing used on cancel paths.

Overview
Adds TemporalOperationHandler, a composable Nexus OperationHandler that wires a user-defined start lambda to Temporal via TemporalNexusClient (typed/untyped startWorkflow overloads) and TemporalOperationResult (sync vs async operation token). Cancel paths parse tokens with a generalized OperationToken / loadOperationToken, dispatch workflow-run cancels through overridable cancelWorkflowRun, and default behavior cancels the backing workflow.

Shared “start workflow + attach Nexus links” logic moves into NexusStartWorkflowHelper, which WorkflowRunOperationImpl now uses instead of inlined code. TemporalNexusClientImpl enforces one async start per handler invocation (extra starts fail with BAD_REQUEST; the guard resets if start fails).

All new public Nexus APIs are marked @Experimental. Integration tests cover typed/untyped starts, void workflows, sync results, cancel, and double-start rejection.

^{Reviewed by Cursor Bugbot for commit 71ab56f. Bugbot is set up for automated code reviews on this repo. Configure here.}

VegetarianOrc

Looks great. Couple small questions mostly for my learning!

VegetarianOrc · 2026-05-22T16:54:00Z

    if (Strings.isNullOrEmpty(token.getWorkflowId())) {
-      throw new IllegalArgumentException("Invalid workflow run token: missing workflow ID (wid)");
+      throw new IllegalArgumentException("Invalid operation token: missing workflow ID (wid)");


Should this check be moved into loadWorkflowRunOperationToken?

VegetarianOrc · 2026-05-22T17:56:22Z

+  /**
+   * Returns the synchronous result value, or null if this is an async result.
+   *
+   * @return the sync result value, or null
+   */
+  @Nullable
+  public R getSyncResult() {
+    return syncResult;
+  }
+
+  /**
+   * Returns the async operation token, or null if this is a sync result.
+   *
+   * @return the operation token, or null
+   */
+  @Nullable
+  public String getAsyncOperationToken() {
+    return asyncOperationToken;
+  }


Just a style question to familiarize myself with Java a bit more: Should these throw if invoked on the wrong type of result? i.e. should getAsyncOperationToken throw if isSync == true?

Agreed, it would be more idiomatic to check and throw. We can then remove @Nullable annotations from the methods too.

VegetarianOrc · 2026-05-22T17:58:57Z


-  public WorkflowRunOperationToken(String namespace, String workflowId) {
-    this.type = OperationTokenType.WORKFLOW_RUN;
+  public OperationToken(OperationTokenType type, String namespace, String workflowId) {


With more types of tokens upcoming, should we favor something like static constructors for this like OperationToken.NewWorkflowRunToken() that takes the required fields for the workflow run type?

I guess this is a bit like what OperationTokenUtil provides so feel free to dismiss this!

maciejdudko

Looks good, only a few small changes needed.

maciejdudko · 2026-06-04T21:00:27Z

+  /**
+   * Returns the synchronous result value, or null if this is an async result.
+   *
+   * @return the sync result value, or null
+   */
+  @Nullable
+  public R getSyncResult() {
+    return syncResult;
+  }
+
+  /**
+   * Returns the async operation token, or null if this is a sync result.
+   *
+   * @return the operation token, or null
+   */
+  @Nullable
+  public String getAsyncOperationToken() {
+    return asyncOperationToken;
+  }


Agreed, it would be more idiomatic to check and throw. We can then remove @Nullable annotations from the methods too.

cursor

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{Reviewed by Cursor Bugbot for commit 10a94e4. Configure here.}

Quinn-With-Two-Ns marked this pull request as ready for review April 14, 2026 22:33

Quinn-With-Two-Ns requested a review from a team as a code owner April 14, 2026 22:33

Quinn-With-Two-Ns commented Apr 14, 2026

View reviewed changes

Comment thread temporal-sdk/src/test/java/io/temporal/workflow/nexus/GenericHandlerTypedProcTest.java Outdated

cursor Bot reviewed Apr 14, 2026

View reviewed changes

Comment thread temporal-sdk/src/test/java/io/temporal/internal/nexus/WorkflowRunTokenTest.java

Comment thread temporal-sdk/src/test/java/io/temporal/workflow/nexus/AsyncWorkflowOperationTest.java Outdated

cursor Bot reviewed Apr 14, 2026

View reviewed changes

Comment thread temporal-sdk/src/test/java/io/temporal/workflow/nexus/AsyncWorkflowOperationTest.java Outdated

cursor Bot reviewed Apr 16, 2026

View reviewed changes

Comment thread temporal-sdk/src/main/java/io/temporal/internal/nexus/OperationTokenUtil.java

Quinn-With-Two-Ns force-pushed the temporal-nexus-operation-handler branch from a33ff01 to 7e61dab Compare May 8, 2026 14:14

cursor Bot reviewed May 8, 2026

View reviewed changes

Comment thread temporal-sdk/src/main/java/io/temporal/nexus/TemporalOperationHandler.java

Quinn-With-Two-Ns requested a review from bergundy May 11, 2026 15:09

VegetarianOrc reviewed May 12, 2026

View reviewed changes

Comment thread temporal-sdk/src/main/java/io/temporal/nexus/TemporalNexusClientImpl.java Outdated

Quinn-With-Two-Ns force-pushed the temporal-nexus-operation-handler branch from 7e61dab to f2c65fc Compare May 15, 2026 23:04

cursor Bot reviewed May 15, 2026

View reviewed changes

Comment thread temporal-sdk/src/main/java/io/temporal/nexus/TemporalNexusClientImpl.java Outdated

bergundy removed their request for review May 20, 2026 19:14

VegetarianOrc approved these changes May 22, 2026

View reviewed changes

cursor Bot reviewed May 29, 2026

View reviewed changes

Comment thread temporal-sdk/src/main/java/io/temporal/nexus/TemporalNexusClientImpl.java

Quinn-With-Two-Ns requested a review from maciejdudko May 29, 2026 20:37

maciejdudko requested changes Jun 4, 2026

View reviewed changes

Quinn-With-Two-Ns requested a review from maciejdudko June 4, 2026 22:42

cursor Bot reviewed Jun 4, 2026

View reviewed changes

Comment thread temporal-sdk/src/main/java/io/temporal/nexus/TemporalNexusClientImpl.java

maciejdudko approved these changes Jun 5, 2026

View reviewed changes

Quinn-With-Two-Ns added 10 commits June 11, 2026 08:30

Add Temporal Nexus Operation Handler

50e011d

Update

a216ddc

Update some docs

ac84bea

Update calling convention

aaf2f76

Code review

5f8202e

Address feedback

ec8756a

Add check for duplicate handler start

18a9894

Add check for duplicate handler start

b3c096d

Fix race

ab81e28

Switch to CancelWorkflowRunInput

5d4eb88

Quinn-With-Two-Ns added 3 commits June 11, 2026 08:30

Switch to CancelWorkflowRunInput

da0391a

Respond to PR comments

e994bad

remove references to io.nexusrpc

71ab56f

Quinn-With-Two-Ns force-pushed the temporal-nexus-operation-handler branch from 10a94e4 to 71ab56f Compare June 11, 2026 15:30

Quinn-With-Two-Ns merged commit 27cfa7d into temporalio:master Jun 11, 2026
18 checks passed

Uh oh!

Conversation

Quinn-With-Two-Ns commented Apr 14, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Add TemporalOperationHandler for generic Nexus operations

Goal

Summary

Test plan

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

VegetarianOrc left a comment

Choose a reason for hiding this comment

Uh oh!

VegetarianOrc May 22, 2026

Choose a reason for hiding this comment

Uh oh!

VegetarianOrc May 22, 2026

Choose a reason for hiding this comment

Uh oh!

maciejdudko Jun 4, 2026

Choose a reason for hiding this comment

Uh oh!

Quinn-With-Two-Ns Jun 4, 2026

Choose a reason for hiding this comment

Uh oh!

VegetarianOrc May 22, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

maciejdudko left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

maciejdudko Jun 4, 2026

Choose a reason for hiding this comment

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Quinn-With-Two-Ns commented Apr 14, 2026 •

edited by cursor Bot

Loading